﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace OOLib
{
   /// <summary>
   /// Offers a simple way to store a component to an URL
   /// </summary>
   /// <remarks>
   /// It is usually only useful for two cases: 
   /// 1. Large components which are wrapped up in UNO interfaces and for which distinct filters are not available separately as components. 
   /// 2. Very small components for which only one or very few hard coded file format filters make sense or even exist.
   /// </remarks>
   public interface IStorable
   {
      /// <summary>
      /// Gets if object knows the location because it was loaded from there, or because it is stored there.
      /// </summary>
      bool HasLocation { get; }

      /// <summary>
      /// After XStorable::storeAsURL() it returns the URL the object was stored to.
      /// </summary>
      /// <returns>Returns the URL of the resource which is represented by this object.</returns>
      string GetLocation();

      /// <summary>
      /// Gets if the data store is readonly or opened readonly.
      /// </summary>
      /// <remarks>
      /// It is not possible to call XStorable::store() successfully when the data store is read-only. 
      /// </remarks>
      bool IsReadonly { get; }

      /// <summary>
      /// Stores the data to the URL from which it was loaded.
      /// </summary>
      /// <remarks>
      /// Only objects which know their locations can be stored.
      /// </remarks>
      void Store();

      /// <summary>
      /// Stores the object's persistent data to a URL and makes this URL the new location of the object. 
      /// </summary>
      /// <param name="url">Specifies the new location of this component as url.</param>
      /// <param name="arguments">Optional parameters for saving (see ::com::sun::star::document::MediaDescriptor for further details)</param>
      /// <remarks>
      /// This is the normal behavior for UI's "save-as" feature.
      /// The change of the location makes it necessary to store the document in a format that the object can load. 
      /// For this reason the implementation of XStorable::storeAsURL() will throw an exception if a pure export filter is used, 
      /// it will accept only combined import/export filters. For such filters the method XStorable::storeToURL() must be 
      /// used that does not change the location of the object.
      /// </remarks>
      void StoreAsUrl(string url, object[] arguments = null);

      /// <summary>
      /// Stores the object's persistent data to a file and makes this file the new location of the object. 
      /// </summary>
      /// <param name="fileName">Specifies the new location of this component as file name.</param>
      /// <param name="arguments">Optional parameters for saving (see ::com::sun::star::document::MediaDescriptor for further details)</param>
      /// <remarks>
      /// This is the normal behavior for UI's "save-as" feature.
      /// The change of the location makes it necessary to store the document in a format that the object can load. 
      /// For this reason the implementation of XStorable::storeAsURL() will throw an exception if a pure export filter is used, 
      /// it will accept only combined import/export filters. For such filters the method XStorable::storeToURL() must be 
      /// used that does not change the location of the object.
      /// </remarks>
      void StoreAsFileName(string fileName, object[] arguments = null);

      /// <summary>
      /// Stores the object's persistent data to a URL and continues to be a representation of the old URL. 
      /// </summary>
      /// <param name="url">Specifies the new location of this component as url.</param>
      /// <param name="arguments">Optional parameters for saving (see ::com::sun::star::document::MediaDescriptor for further details)</param>
      /// <remarks>
      /// This is the normal behavior for UI's export feature.
      /// This method accepts all kinds of export filters, not only combined import/export filters because it 
      /// implements an exporting capability, not a persistence capability.
      /// </remarks>
      void StoreToUrl(string url, object[] arguments = null);

      /// <summary>
      /// Stores the object's persistent data to a file and continues to be a representation of the old URL. 
      /// </summary>
      /// <param name="fileName">Specifies the new location of this component as file name.</param>
      /// <param name="arguments">Optional parameters for saving (see ::com::sun::star::document::MediaDescriptor for further details)</param>
      /// <remarks>
      /// This is the normal behavior for UI's export feature.
      /// This method accepts all kinds of export filters, not only combined import/export filters because it 
      /// implements an exporting capability, not a persistence capability.
      /// </remarks>
      void StoreToFileName(string fileName, object[] arguments = null);
   }
}
